BCI NET 2/BCI NET 2.iso/archives/applications/wp/pmtex.lha/pmtex/doc/pmtex.txt

Text File | 1995-02-28 | 10.8 KB | 202 lines

                               PMTeX
                    A Preprocessor for MusicTeX
                by Don Simons ([e-mail])

INTRODUCTION
     PMTeX will generate MusicTeX code for multi-staff scores with up to
five staves (or voices) per system.  Once it makes a .tex file for you,
you will probably want or need to change a few things manually.  This is
because (a) PMTeX only has a small subset of the capabilities of
MusicTeX, and (b) PMTeX is not perfect.  But it can save a LOT of time
with the grunge work involved in setting up notes...enotes groupings,
defining beams, justifying lines, and spreading the entire piece evenly
over a specified number of systems.
     PMTeX can deal with one and only one melody per staff (voice).  It
won't let you change the time signature or key signature within a piece.
Except the first bar, every bar in each staff must have exactly the
number of beats specified by the input parameter mtrnum.  On the first
pass pmtexa will choke if these timings or just about anything else is
askew in the input.  The error messages are not especially pointed, so
it is best to enter only a few bars at a time, run pmtexa, correct
errors, rerun, etc.
     You can enter note values and rests from whole notes to 32nds, and
trills and mordents.  Since I'm interested in baroque chamber music, I
built in the ability to notate figured bass below the bottom staff in
each system.

SETUP
     The distribution contains the files pmtexa.for, pmtexb.for,
pmtex.inc, sample.inp, and pmtex.tex.  First compile the two FORTRAN
programs (with the .inc file accessible to the compiler).  I used
Microsoft FORTRAN to develop the code, and have checked that it works on
an IBM RISC 6000 when compiled with xlf.  I hope the code is generic
enough that it will work with other systems.  Put the executables either
in your working directory or somewhere in the path.  Put pmtex.tex into
the texinput directory.  Put sample.inp into your working directory (the
one from which you will run PMTeX.  Edit the 7th line of sample.inp to
contain the path to the texinput directory; the code will put the .tex
file there. If you want this to be the same as the working directory,
type '.\' for DOS, or './' for UNIX (don't type the quotes).  If you
have a conventional PCTeX setup you would enter 'c:\pctex\texinput\',
etc.  Next run the first pass by typing 'pmtexa'.  You will be prompted
for a basename; for the sample it is 'sample'.  If pmtexa runs
successfully it will generate two files in the working directory,
pmtex.fig and pmtex.dat.  Next run pmtexb by typing 'pmtexb'.  This will
put sample.tex and sample.fig into the texinput directory (.fig only if
you have figured bass).  Now you are right where you would be after
manually entering, debugging, and rough-editing any .tex file.  To see
the results, 'tex' the file sample.tex.  You'll notice that two systems
on each of the two pages are a little too long.  That's not your fault;
I left things that way just to PROVE that PMTeX isn't perfect.  To fix
them, manually increase the first autolines parameter for each of these
lines by one.

WHAT GOES INTO AN INPUT FILE
     Let's just go through sample.inp.  It will take a while, but we'll
cover practically all the possible inputs.  For reference, here are the
first 9 lines of the file:

3 3 4 4 6 1 3
5 10 20 0.07
Basso
Violin II
Violin I
btt
c:\pctex\texinput\
%     read(10,*)nv,noinst,mtrnum,mtrden,imeter,xmtrnum0,isig,
%    *          lpp,nstaves,musicsize,fracindent

These are the setup data.  The lines with % in column 1 are comments.
You can only put comments AFTER the end of the initial data section.
Starting in the first line,

nv (integer<6) is the number of voices, or staves per system.

noinst (integer<6) is number of 'instruments'.  All this does is choose
     whether you want a brace in front of each system (noinst=1) or not
     (noinst>1).

mtrnum is the numerator of the time signature, mtrden the denominator.
     So far I've only tested 3/4, 6/8, 2/2, 2/4, and 4/4 but others may
     work.

imeter determines how the time signature looks:
     0           Fraction
     2, 3, or 4  Just that number, between the 2nd and 4th lines
     5           Common time
     6           Cut time (alla breve)

xmtrnum0 is the number of beats in the first bar, but only if there's
     a pickup; otherwise set it to 0 .  I had intended fractions to work
     but they don't seem to, just integers.  The first bar is the ONLY
     bar that can have a different number of beats.

isig is the key signature, positive integer for sharps, negative for
     flats.

lpp is the number of systems per page.

nstaves is a misnomer (I just realized): it's really the total number of
     systems in the whole piece.  Leftovers start at the front, so for
     example if lpp=3 and nstaves=5 there will 3 systems on the first
     page.  WARNING: if you are building an input file one gulp at a
     time, you will have to adjust this parameter to roughly reflect the
     CURRENT number of staves.  If nstaves is too big for the current
     number of bars. the code will choke.

musicsize is 20 or 16 (height of a staff in points).

fracindent is the fraction of the total line width to indent the first
     line.

     Next come the names of the nv instruments as you want them to
appear within the indentation in the first system, one per line,
starting with the BOTTOM voice.  Then a string of nv letters for the
clefs, again starting with the bottom voice: 'b' for bass, 'a' for alto,
't' for treble.
     Line 7 in sample.inp is the last of the setup data, the path to the
.tex directory, where you want sample.tex to go when pmtex makes it.
The rest of sample.inp is the body of the input.  You feed it music in
gulps of an integral number of bars, usually 4 to 8.  If you give it too
big a gulp, it will choke (due to dimension limits), and there aren't
any internal dimension checks.  (I've been bitten by this one myself).
Each gulp has some stuff for a few bars of the first (lowest) voice,
then a '/', then the second voice for EXACTLY the same number of bars,
another '/', and so on for nv voices.  When the last (top) voice
finishes (with a '/') the gulp is ready for digestion.
     The stuff for each voice is a sequence of "symbols" of one or more
adjacent characters, separated by spaces.  Separate the voice-
terminating '/' with spaces just to be safe.
     Note symbols always start with a letter and end at the first space.
The letter has the obvious meaning (unlike another entry system we all
know about, which unfortunately I could never get comfortable with and
believe me I did try but I guess I'm getting too old).  Next is a digit
for the octave...middle C is c4, the B just below is b3.  If a note is
the same length and within a fourth of its predecessor, the symbol can
be one letter only, provided it doesn't have an accidental.  This makes
it really easy to enter long strings of scalewise or even arpeggiated
notes of equal value: letter,space,letter,space...  If a note is the
same length but more than a fourth away from its predecessor, and again
no accidental, the note symbol can be just two characters long, the note
name and the octave.  Next comes a digit for the length (if needed): 0
for whole, 2 for half, 4 for quarter, 8 for eighth, 1 for sixteenth, and
3 for thirty-second notes (with credit to Dr. T's Copyist Apprentice, my
first foray into notation programs.  Actually it seems really cool to me
that these digits don't bump into each other but still cover all normal
possibilities.)  (Sorry, we don't do triplets.  If you just have a few
triplets, enter something else and fix them by hand later.  If there are
a lot of triplets you could try using a separate file for that section,
faking out the code with a different time signature--say 6/8 instead of
2/4--then manually merging the .tex files later.)  The next two
characters (if needed) are letters to signal a dot ('d') and/or
accidental ('f':flat, 'n':natural, 's':sharp).  If both are present they
can be in either order.  If either is present then the first three
characters--note, octave, duration--are required.  Don't enter an
accidental if it's in the key signature.  Advanced users can change the
behavior of the accidentals to 'smart' (transposable) from literal (the
default) by editing pmtex.tex.  (With the baroque convention for
accidentals, 'smart' ones don't work even if you're not transposing!)
The code tries to put in extra horizontal space if needed to make room
for accidentals.
     After a note symbol goes any associated ornament or figure.  The
only ornaments are trill ('ot') and mordent ('om').  (Minimal
programming could expand this list, but I haven't needed any others).
All accidentals will come out just high enough above the staff not to
crash into their notes.
     A rest symbol has two characters, just 'r' followed by a digit for
its length, using the same code as for note values.

FIGURED BASS
     Figure symbols follow their associated note symbols.  They only
work in the first (lowest) voice.  Enter the characters as they would
appear from top to bottom, and as you might pronounce them, e.g., '64'
or '73'.  Flats here are '-' (minus), sharps are '#', and naturals 'n',
BEFORE the number (if there is a number) (perversity or absentmindedness
is why they're different here than in note symbols).  So six (over) flat
five is  '6-5' as in the first line of the body of sample.inp, and sharp
six (over) 4 is '#64'.  The program prints all the figures for each
system below the lowest staff, with their tops aligned, and just low
enough to clear the lowest beam, notehead, or stem that could interfere.
(This was kind of tricky to program!)

A WORD ABOUT SLURS AND TIES
     There's no provision for them in PMTeX.  Why?  I handle them with
another code that post-processes the postscript file.  That code will
only run on a PC with VGA graphics.  If there is interest, I'll
distribute it later.  But for now, sorry, you're on your own.  At worst,
you can enter MusicTeX slur codes manually.

TH-TH-THAT'S ALL, FOLKS
     There's not much more to say about basic care and feeding of PMTeX.
One suggestion worth repeating is to enter just a few bars at a time,
and at least run them through pmtexa to get rid of typos.  If you wanted
to type a lot at once, you could comment out all gulps but the first,
then delete comment symbols a gulp at a time, letting PMTeX digest the
gulps one-by-one.  Unless you never make mistakes.
     Please hit me with questions, bugs, and comments. I'll consider
suggestions for additions as time and inclination permit.  I am thinking
about improving the input checking in pmtexa.  There is one thing I hope
I don't hear: that after trying the program you think my silly
gastrointestinal metaphor should be carried to its logical "end" when
describing PMTeX's output.